Day 1：擁抱框架：認識 LangChain4j 與設定開發環境

Java AI 核心引擎：30 天從零打造可擴展的智慧 Agent 函式庫
本篇是 IT 鐵人賽系列文章的第一天，將建立一個能與本地語言模型溝通的 LangChain4j 專案基礎。
執行指引：本專案支援兩種執行模式：

• 開發模式：./mvnw spring-boot:run -Dspring-boot.run.profiles=dev （專注當天開發內容）
• 完整模式：./mvnw spring-boot:run （體驗累積的完整功能）

今日目標

• 安裝並設定 Ollama 本地 LLM 服務
• 建立 Spring Boot + LangChain4j 專案
• 完成基礎環境配置和驗證

搭建 AI 開發環境：安裝 Ollama

在 Mac 上安裝 Ollama

開始 AI Agent 開發的第一步，就是要有一個本地的語言模型運行環境。Ollama 就是為了解決這個需求而生的工具，它讓我們可以在自己的電腦上輕鬆運行各種大語言模型。

最簡單的安裝方式：使用 Homebrew

brew install ollama

如果你沒有 Homebrew，或是偏好圖形化安裝，也可以直接從官網下載：

https://ollama.com/download

推薦使用 Homebrew，因為後續更新管理都會比較方便。

選擇合適的語言模型

根據 Ollama 官方模型庫，Ollama 支援多種語言模型。在眾多選擇中，推薦使用 Llama 3.1：

ollama run llama3.1:8b-instruct-q4_K_M

Ollama 運行流程

根據 Ollama 官方文件，執行 ollama run 時，Ollama 會自動：

1. 檢查本機模型：確認指定模型是否已存在
2. 自動下載：若不存在，從網路下載並顯示進度條
3. 載入模型：下載完成後自動載入到記憶體
4. 啟動聊天：進入互動式對話模式

載入完成後，會出現 >>> 提示符，此時可以直接與模型對話：

>>> 你好，請用繁體中文介紹一下你自己。

確認一切準備就緒

在繼續開發之前，讓我們花點時間確認 Ollama 服務都正常運作。這些檢查步驟看似簡單，但能避免後續開發時遇到莫名的連線問題。

檢查 API 服務是否啟動
Ollama 會在背景啟動一個 API 服務，預設監聽 11434 端口：

curl http://localhost:11434/api/version

查看已下載的模型

ollama list

檢查正在運行的模型

ollama ps

如果 ollama ps 沒有顯示任何內容，別緊張！這表示目前沒有模型載入記憶體中，這是正常現象。Ollama 採用的是按需載入的策略，只有在實際需要時才會將模型載入記憶體。

建立我們的 Spring Boot 專案

使用 IntelliJ IDEA 快速起步

接下來建立一個 Spring Boot 專案作為 AI Agent 框架的基礎。雖然市面上有很多建立 Spring Boot 專案的方式，但使用 IntelliJ IDEA 的內建嚮導是最直觀的方式。

建立專案的步驟如下：

1. 開啟 IntelliJ IDEA，選擇 New Project

2. 選擇專案類型：

   • Generators: Spring Boot（這會使用 Spring Initializr）
   • Language: Java（我們的主角）
   • Type: Maven（依賴管理工具）
   • JDK: 21（長期支援版本，功能豐富）
   • Spring Boot Version: 3.5.4（最新穩定版）

3. 添加基礎依賴：

   • 勾選 Spring Web（雖然今天用不到，但後面會需要）

4. 設定專案資訊：

   • Group: org.example
   • Artifact: ai-agent-demo
   • Name: ai-agent-demo
   • Package name: org.example.aiagentdemo

5. 按下 Create 完成專案建立

整個過程大概需要一兩分鐘，IDEA 會幫我們下載相關依賴並建立好專案結構。

新增 LangChain4j 依賴

編輯 pom.xml

Maven 依賴資料來源

根據 Maven Central Repository，LangChain4j 0.36.2 版本提供以下官方 Spring Boot Starter：

• langchain4j-spring-boot-starter
• langchain4j-ollama-spring-boot-starter

實際依賴配置

在專案根目錄的 pom.xml 中，於 <dependencies> 區段新增：

<!-- LangChain4j Spring Boot Starter -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.36.2</version>
</dependency>

<!-- LangChain4j Ollama Spring Boot Starter -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama-spring-boot-starter</artifactId>
    <version>0.36.2</version>
</dependency>

應用程式配置

編輯 application.properties

配置參數資料來源

根據 LangChain4j Spring Boot Integration 文件，Ollama 整合支援以下官方配置參數：

• langchain4j.ollama.chat-model.base-url： Ollama 服務的基礎 URL
• langchain4j.ollama.chat-model.model-name：要使用的模型名稱

對於其他參數如 temperature 和 timeout, 見 Ollama Modelfile 文件。

實際配置範例

在 src/main/resources/application.properties 中新增 Ollama 配置：

spring.application.name=ai-agent-demo

# === LangChain4j Ollama 配置 ===

# 基礎連線設定
langchain4j.ollama.chat-model.base-url=http://localhost:11434
langchain4j.ollama.chat-model.model-name=llama3.1:8b-instruct-q4_K_M

# 模型參數設定（詳細說明請參閱 Day 5）
langchain4j.ollama.chat-model.temperature=0.7
langchain4j.ollama.chat-model.timeout=PT5M

系統提示詞機制說明

系統訊息（System Message）的作用是指示大語言模型如何表現

在我們的實作中，透過 @SystemMessage 註解可以輕鬆設定 AI 的角色和行為準則。

環境驗證與測試

1. 編譯專案

./mvnw clean compile

預期結果：BUILD SUCCESS

2. 啟動應用程式

建議使用開發模式：

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

或使用完整模式：

./mvnw spring-boot:run

看到 Spring Boot 啟動 logo 和 Started AiAgentDemoApplication 訊息表示成功。

3. 驗證檢查清單

Ollama 環境檢查：

# 確認 API 服務運行
curl http://localhost:11434/api/version

# 確認模型存在
ollama list

專案環境檢查：

# 確認 Java 版本
java --version

# 確認 Maven 可用
./mvnw --version

總結

今日完成項目

我們已經成功完成了以下設定：

1. Ollama App 與模型下載：安裝 Ollama 並下載 Llama 3.1 8B 模型
2. Ollama 服務運行：API 服務在 localhost:11434 正常運作
3. Spring Boot + LangChain4j 整合：專案編譯成功，依賴配置正確

環境驗證

快速驗證指令：

ollama list                                               # 確認模型存在
./mvnw clean compile                                     # 確認專案編譯成功
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev   # 確認服務啟動正常（開發模式）

明日預告：Day 2 - 首次 AI 對話

明天我們將：

• 建立第一個 ChatLanguageModel Bean
• 實現基本的 AI 對話功能
• 透過 CommandLineRunner 測試模型回應
• 體驗 LangChain4j 與 Ollama 的整合效果！

恭喜你完成了 AI Agent 開發的第一步！

參考資料

• LangChain4j Spring Boot Starter (穩定版)
• LangChain4j Ollama Integration 官方文件
• Ollama 官方網站
• Spring Boot 3.5.4 官方文件

感謝大家的閱讀，我們明天見！

Day 1 完成 | 明天繼續我們的 AI 冒險之旅！